@lensjs/core 1.0.12 → 2.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @lensjs/core
+
+The core library for Lens, providing the fundamental architecture for monitoring and debugging applications. It defines the abstract concepts of adapters, stores, and watchers, along with utilities for event emission, asynchronous context management, and SQL formatting. This package also includes the embedded UI for the Lens dashboard.
+
+## Features
+
+*   **`Lens` class**: The central class for initializing Lens, setting up adapters and watchers, and starting the monitoring process.
+*   **`LensAdapter` (abstract class)**: Defines the interface for integrating Lens with different application frameworks (e.g., Express, Adonis). It handles route registration and UI serving.
+*   **`LensStore` (abstract class)**: Defines the interface for data storage, allowing Lens to persist and retrieve captured events (requests, queries, cache entries). Includes methods for saving, retrieving, and truncating data.
+*   **`LensWatcher` (abstract class)**: Defines the interface for capturing specific types of events within an application.
+*   **Concrete Watchers**:
+    *   `RequestWatcher`: Captures and logs details of incoming HTTP requests.
+    *   `QueryWatcher`: Captures and logs database queries.
+    *   `CacheWatcher`: Captures and logs cache interactions.
+    *   `ExceptionWatcher`: Captures and logs exceptions and errors.
+*   **`ApiController`**: Provides the API endpoints for the Lens UI to fetch monitoring data.
+*   **`lensEmitter`**: A global event emitter for internal communication between different parts of Lens.
+*   **`lensContext`**: Utilizes `AsyncLocalStorage` for managing asynchronous context, primarily to associate events with a specific request ID.
+*   **`lensUtils`**: A collection of utility functions, including:
+    *   `generateRandomUuid`: Generates unique IDs.
+    *   `interpolateQuery`: Interpolates SQL query placeholders with actual values.
+    *   `formatSqlQuery`: Formats SQL queries for readability.
+    *   `getMeta`: Provides `__filename` and `__dirname` in both CommonJS and ESM environments.
+    *   `isStaticFile`, `stripBeforeAssetsPath`: Utilities for handling static file paths.
+    *   `prepareIgnoredPaths`, `shouldIgnoreCurrentPath`: Logic for path-based filtering.
+    *   `prettyHrTime`: Formats high-resolution time differences.
+*   **`BetterSqliteStore`**: A concrete implementation of `LensStore` using Better SQLite for data persistence.
+*   **Embedded UI**: Includes a built-in web interface for visualizing captured application data.
+
+## Installation
+
+```bash
+pnpm add @lensjs/core
+```
+
+## Usage Example (Conceptual - typically used via framework adapters)
+
+```typescript
+import { Lens, RequestWatcher, QueryWatcher, CacheWatcher } from '@lensjs/core';
+import { BetterSqliteStore } from '@lensjs/core/stores';
+// Assuming you have a custom adapter for your framework
+import MyFrameworkAdapter from './my-framework-adapter';
+
+async function bootstrapLens(appInstance: any) {
+  const store = new BetterSqliteStore();
+  await store.initialize();
+
+  const adapter = new MyFrameworkAdapter({ app: appInstance });
+
+  await Lens.setStore(store)
+    .setAdapter(adapter)
+    .setWatchers([
+      new RequestWatcher(),
+      new QueryWatcher(),
+      new CacheWatcher(),
+      new ExceptionWatcher(),
+    ])
+    .start({
+      appName: 'My Application',
+      enabled: process.env.NODE_ENV !== 'production',
+      basePath: 'lens-dashboard', // UI will be served at /lens-dashboard
+    });
+
+  console.log('Lens core initialized.');
+}
+
+// In your application's main entry point:
+// bootstrapLens(yourFrameworkAppInstance);
+```

package/dist/abstracts/store.cjs

@@ -24,4 +24,27 @@ __export(store_exports, {
 });
 module.exports = __toCommonJS(store_exports);
 var Store = class {
+  getAllExceptions(_paginationParams) {
+    return this.defaultMinimalPaginate();
+  }
+  stringifyData(data) {
+    if (typeof data === "string") {
+      return data;
+    }
+    try {
+      return JSON.stringify(data);
+    } catch (e) {
+      console.error(`Failed to stringify lens data: ${e}`);
+    }
+  }
+  defaultMinimalPaginate() {
+    return Promise.resolve({
+      data: [],
+      meta: {
+        currentPage: 0,
+        lastPage: 0,
+        total: 0
+      }
+    });
+  }
 };

package/dist/abstracts/store.d.cts

@@ -1,6 +1,7 @@
 import { WatcherTypeEnum, PaginationParams, Paginator, LensEntry } from '../types/index.cjs';
 import 'sql-formatter';
 
+type MinimalPaginatePromise = Promise<Paginator<Omit<LensEntry, "data">[]>>;
 declare abstract class Store {
     abstract initialize(): Promise<void>;
     abstract save(entry: {
@@ -11,13 +12,17 @@ declare abstract class Store {
         timestamp?: string;
         requestId?: string;
     }): Promise<void>;
-    abstract getAllRequests(paginationParams: PaginationParams): Promise<Paginator<Omit<LensEntry, "data">[]>>;
+    abstract getAllRequests(paginationParams: PaginationParams): MinimalPaginatePromise;
     abstract getAllQueries(paginationParams: PaginationParams): Promise<Paginator<LensEntry[]>>;
-    abstract allByRequestId(requestId: string, type: WatcherTypeEnum): Promise<LensEntry[]>;
+    abstract getAllCacheEntries(paginationParams: PaginationParams): MinimalPaginatePromise;
+    abstract allByRequestId(requestId: string, type: WatcherTypeEnum, includeFullData?: boolean): Promise<LensEntry[]>;
     abstract find(type: WatcherTypeEnum, id: string): Promise<LensEntry | null>;
     abstract truncate(): Promise<void>;
     abstract paginate<T>(type: WatcherTypeEnum, pagination: PaginationParams): Promise<Paginator<T>>;
     abstract count(type: WatcherTypeEnum): Promise<number>;
+    getAllExceptions(_paginationParams: PaginationParams): MinimalPaginatePromise;
+    protected stringifyData(data: Record<string, any> | string): string | undefined;
+    protected defaultMinimalPaginate(): MinimalPaginatePromise;
 }
 
 export { Store as default };

package/dist/abstracts/store.d.ts

@@ -1,6 +1,7 @@
 import { WatcherTypeEnum, PaginationParams, Paginator, LensEntry } from '../types/index.js';
 import 'sql-formatter';
 
+type MinimalPaginatePromise = Promise<Paginator<Omit<LensEntry, "data">[]>>;
 declare abstract class Store {
     abstract initialize(): Promise<void>;
     abstract save(entry: {
@@ -11,13 +12,17 @@ declare abstract class Store {
         timestamp?: string;
         requestId?: string;
     }): Promise<void>;
-    abstract getAllRequests(paginationParams: PaginationParams): Promise<Paginator<Omit<LensEntry, "data">[]>>;
+    abstract getAllRequests(paginationParams: PaginationParams): MinimalPaginatePromise;
     abstract getAllQueries(paginationParams: PaginationParams): Promise<Paginator<LensEntry[]>>;
-    abstract allByRequestId(requestId: string, type: WatcherTypeEnum): Promise<LensEntry[]>;
+    abstract getAllCacheEntries(paginationParams: PaginationParams): MinimalPaginatePromise;
+    abstract allByRequestId(requestId: string, type: WatcherTypeEnum, includeFullData?: boolean): Promise<LensEntry[]>;
     abstract find(type: WatcherTypeEnum, id: string): Promise<LensEntry | null>;
     abstract truncate(): Promise<void>;
     abstract paginate<T>(type: WatcherTypeEnum, pagination: PaginationParams): Promise<Paginator<T>>;
     abstract count(type: WatcherTypeEnum): Promise<number>;
+    getAllExceptions(_paginationParams: PaginationParams): MinimalPaginatePromise;
+    protected stringifyData(data: Record<string, any> | string): string | undefined;
+    protected defaultMinimalPaginate(): MinimalPaginatePromise;
 }
 
 export { Store as default };

package/dist/abstracts/store.js

@@ -1,5 +1,28 @@
 // src/abstracts/store.ts
 var Store = class {
+  getAllExceptions(_paginationParams) {
+    return this.defaultMinimalPaginate();
+  }
+  stringifyData(data) {
+    if (typeof data === "string") {
+      return data;
+    }
+    try {
+      return JSON.stringify(data);
+    } catch (e) {
+      console.error(`Failed to stringify lens data: ${e}`);
+    }
+  }
+  defaultMinimalPaginate() {
+    return Promise.resolve({
+      data: [],
+      meta: {
+        currentPage: 0,
+        lastPage: 0,
+        total: 0
+      }
+    });
+  }
 };
 export {
   Store as default

package/dist/core/api_controller.cjs

@@ -74,14 +74,30 @@ var ApiController = class {
       await getStore().getAllRequests(this.extractPaginationParams(qs))
     );
   }
-  static async getRequest({
-    params
-  }) {
+  static async getRequest({ params }) {
     const request = await getStore().find("request" /* REQUEST */, params.id);
     if (!request) {
       return this.notFoundResponse();
     }
-    return this.resourceResponse(request);
+    const queries = await getStore().allByRequestId(
+      request.id,
+      "query" /* QUERY */
+    );
+    const cacheEntries = await getStore().allByRequestId(
+      request.id,
+      "cache" /* CACHE */
+    );
+    const exceptions = await getStore().allByRequestId(
+      request.id,
+      "exception" /* EXCEPTION */,
+      false
+    );
+    return this.resourceResponse({
+      request,
+      queries,
+      cacheEntries,
+      exceptions
+    });
   }
   static async getQueries({
     qs
@@ -100,6 +116,33 @@ var ApiController = class {
     }
     return this.resourceResponse(query);
   }
+  static async getCacheEntries({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllCacheEntries(this.extractPaginationParams(qs))
+    );
+  }
+  static async getCacheEntry({ params }) {
+    const cacheEntry = await getStore().find("cache" /* CACHE */, params.id);
+    if (!cacheEntry) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(cacheEntry);
+  }
+  static async getExceptions({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllExceptions(this.extractPaginationParams(qs))
+    );
+  }
+  static async getException({ params }) {
+    const exception = await getStore().find(
+      "exception" /* EXCEPTION */,
+      params.id
+    );
+    if (!exception) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(exception);
+  }
   static async truncate() {
     await getStore().truncate();
     return this.baseResponse({}, 200, "All entries cleared");

package/dist/core/api_controller.d.cts

@@ -1,11 +1,15 @@
-import { RouteDefinitionHandler, ApiResponse, LensEntry } from '../types/index.cjs';
+import { RouteDefinitionHandler, ApiResponse, LensEntry, Paginator } from '../types/index.cjs';
 import 'sql-formatter';
 
 declare class ApiController {
     static getRequests({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
-    static getRequest({ params, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry>>;
+    static getRequest({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
     static getQueries({ qs, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry[]>>;
     static getQuery({ params, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry>>;
+    static getCacheEntries({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
+    static getCacheEntry({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
+    static getExceptions({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
+    static getException({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
     static truncate(): Promise<ApiResponse<{}>>;
     static fetchUiConfig(): {
         appName: string;
@@ -18,7 +22,7 @@ declare class ApiController {
     private static extractPaginationParams;
     private static resourceResponse;
     private static notFoundResponse;
-    private static paginatedResponse;
+    static paginatedResponse<T extends Object>(data: Paginator<T>): ApiResponse<T>;
     private static baseResponse;
 }
 

package/dist/core/api_controller.d.ts

@@ -1,11 +1,15 @@
-import { RouteDefinitionHandler, ApiResponse, LensEntry } from '../types/index.js';
+import { RouteDefinitionHandler, ApiResponse, LensEntry, Paginator } from '../types/index.js';
 import 'sql-formatter';
 
 declare class ApiController {
     static getRequests({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
-    static getRequest({ params, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry>>;
+    static getRequest({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
     static getQueries({ qs, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry[]>>;
     static getQuery({ params, }: RouteDefinitionHandler): Promise<ApiResponse<LensEntry>>;
+    static getCacheEntries({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
+    static getCacheEntry({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
+    static getExceptions({ qs }: RouteDefinitionHandler): Promise<ApiResponse<Omit<LensEntry, "data">[]>>;
+    static getException({ params }: RouteDefinitionHandler): Promise<ApiResponse<Object>>;
     static truncate(): Promise<ApiResponse<{}>>;
     static fetchUiConfig(): {
         appName: string;
@@ -18,7 +22,7 @@ declare class ApiController {
     private static extractPaginationParams;
     private static resourceResponse;
     private static notFoundResponse;
-    private static paginatedResponse;
+    static paginatedResponse<T extends Object>(data: Paginator<T>): ApiResponse<T>;
     private static baseResponse;
 }
 

package/dist/core/api_controller.js

@@ -48,14 +48,30 @@ var ApiController = class {
       await getStore().getAllRequests(this.extractPaginationParams(qs))
     );
   }
-  static async getRequest({
-    params
-  }) {
+  static async getRequest({ params }) {
     const request = await getStore().find("request" /* REQUEST */, params.id);
     if (!request) {
       return this.notFoundResponse();
     }
-    return this.resourceResponse(request);
+    const queries = await getStore().allByRequestId(
+      request.id,
+      "query" /* QUERY */
+    );
+    const cacheEntries = await getStore().allByRequestId(
+      request.id,
+      "cache" /* CACHE */
+    );
+    const exceptions = await getStore().allByRequestId(
+      request.id,
+      "exception" /* EXCEPTION */,
+      false
+    );
+    return this.resourceResponse({
+      request,
+      queries,
+      cacheEntries,
+      exceptions
+    });
   }
   static async getQueries({
     qs
@@ -74,6 +90,33 @@ var ApiController = class {
     }
     return this.resourceResponse(query);
   }
+  static async getCacheEntries({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllCacheEntries(this.extractPaginationParams(qs))
+    );
+  }
+  static async getCacheEntry({ params }) {
+    const cacheEntry = await getStore().find("cache" /* CACHE */, params.id);
+    if (!cacheEntry) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(cacheEntry);
+  }
+  static async getExceptions({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllExceptions(this.extractPaginationParams(qs))
+    );
+  }
+  static async getException({ params }) {
+    const exception = await getStore().find(
+      "exception" /* EXCEPTION */,
+      params.id
+    );
+    if (!exception) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(exception);
+  }
   static async truncate() {
     await getStore().truncate();
     return this.baseResponse({}, 200, "All entries cleared");

package/dist/core/lens.cjs

@@ -84,14 +84,30 @@ var ApiController = class {
       await getStore().getAllRequests(this.extractPaginationParams(qs))
     );
   }
-  static async getRequest({
-    params
-  }) {
+  static async getRequest({ params }) {
     const request = await getStore().find("request" /* REQUEST */, params.id);
     if (!request) {
       return this.notFoundResponse();
     }
-    return this.resourceResponse(request);
+    const queries = await getStore().allByRequestId(
+      request.id,
+      "query" /* QUERY */
+    );
+    const cacheEntries = await getStore().allByRequestId(
+      request.id,
+      "cache" /* CACHE */
+    );
+    const exceptions = await getStore().allByRequestId(
+      request.id,
+      "exception" /* EXCEPTION */,
+      false
+    );
+    return this.resourceResponse({
+      request,
+      queries,
+      cacheEntries,
+      exceptions
+    });
   }
   static async getQueries({
     qs
@@ -110,6 +126,33 @@ var ApiController = class {
     }
     return this.resourceResponse(query);
   }
+  static async getCacheEntries({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllCacheEntries(this.extractPaginationParams(qs))
+    );
+  }
+  static async getCacheEntry({ params }) {
+    const cacheEntry = await getStore().find("cache" /* CACHE */, params.id);
+    if (!cacheEntry) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(cacheEntry);
+  }
+  static async getExceptions({ qs }) {
+    return this.paginatedResponse(
+      await getStore().getAllExceptions(this.extractPaginationParams(qs))
+    );
+  }
+  static async getException({ params }) {
+    const exception = await getStore().find(
+      "exception" /* EXCEPTION */,
+      params.id
+    );
+    if (!exception) {
+      return this.notFoundResponse();
+    }
+    return this.resourceResponse(exception);
+  }
   static async truncate() {
     await getStore().truncate();
     return this.baseResponse({}, 200, "All entries cleared");
@@ -161,6 +204,29 @@ var path2 = __toESM(require("path"), 1);
 
 // src/abstracts/store.ts
 var Store = class {
+  getAllExceptions(_paginationParams) {
+    return this.defaultMinimalPaginate();
+  }
+  stringifyData(data) {
+    if (typeof data === "string") {
+      return data;
+    }
+    try {
+      return JSON.stringify(data);
+    } catch (e) {
+      console.error(`Failed to stringify lens data: ${e}`);
+    }
+  }
+  defaultMinimalPaginate() {
+    return Promise.resolve({
+      data: [],
+      meta: {
+        currentPage: 0,
+        lastPage: 0,
+        total: 0
+      }
+    });
+  }
 };
 
 // src/stores/better_sqlite.ts
@@ -183,11 +249,11 @@ var BetterSqliteStore = class extends Store {
       `INSERT INTO ${TABLE_NAME} (id, data, type, created_at, lens_entry_id, minimal_data) values($id, $data, $type, $created_at, $lens_entry_id, $minimalData)`
     ).run({
       id: entry.id ?? (0, import_crypto.randomUUID)(),
-      data: JSON.stringify(entry.data),
+      data: this.stringifyData(entry.data),
       type: entry.type,
-      created_at: entry.timestamp ?? (0, import_date.sqlDateTime)(),
+      created_at: entry.timestamp ?? (0, import_date.nowISO)(),
       lens_entry_id: entry.requestId || null,
-      minimalData: JSON.stringify(entry.minimal_data ?? {})
+      minimalData: this.stringifyData(entry.minimal_data ?? {})
     });
   }
   async getAllQueries(pagination) {
@@ -196,11 +262,17 @@ var BetterSqliteStore = class extends Store {
   async getAllRequests(pagination) {
     return await this.paginate("request" /* REQUEST */, pagination, false);
   }
-  async allByRequestId(requestId, type) {
+  async getAllCacheEntries(pagination) {
+    return await this.paginate("cache" /* CACHE */, pagination);
+  }
+  async getAllExceptions(pagination) {
+    return await this.paginate("exception" /* EXCEPTION */, pagination, false);
+  }
+  async allByRequestId(requestId, type, includeFullData = true) {
     const rows = this.connection.prepare(
-      `${this.getSelectedColumns()} FROM ${TABLE_NAME} WHERE type = $type AND lens_entry_id = $requestId ORDER BY created_at DESC`
+      `${this.getSelectedColumns(includeFullData)} FROM ${TABLE_NAME} WHERE type = $type AND lens_entry_id = $requestId ORDER BY created_at DESC`
     ).all({ type, requestId });
-    return this.mapRows(rows);
+    return this.mapRows(rows, includeFullData);
   }
   async paginate(type, { page, perPage }, includeFullData = true) {
     const offset = (page - 1) * perPage;
@@ -248,8 +320,13 @@ var BetterSqliteStore = class extends Store {
       CREATE INDEX IF NOT EXISTS lens_entries_id_type_index
       ON ${TABLE_NAME} (id, type);
     `;
+    const lensEntryIdIndex = `
+      CREATE INDEX IF NOT EXISTS lens_entry_id_index
+      ON ${TABLE_NAME} (lens_entry_id);
+    `;
     this.connection.exec(createTable);
     this.connection.exec(createIndex);
+    this.connection.exec(lensEntryIdIndex);
   }
   mapRow(row, includeFullData = true) {
     let data = includeFullData ? JSON.parse(row.data) : {};
@@ -356,6 +433,8 @@ var Lens = class {
         api: {
           requests: `/${config.basePath}/api/requests`,
           queries: `/${config.basePath}/api/queries`,
+          cache: `/${config.basePath}/api/cache`,
+          exceptions: `/${config.basePath}/api/exceptions`,
           truncate: `/${config.basePath}/api/truncate`
         }
       };
@@ -388,6 +467,26 @@ var Lens = class {
         path: `${basePath}/api/queries/:id`,
         handler: async (data) => await ApiController.getQuery(data)
       },
+      {
+        method: "GET",
+        path: `${basePath}/api/cache`,
+        handler: async (data) => await ApiController.getCacheEntries(data)
+      },
+      {
+        method: "GET",
+        path: `${basePath}/api/cache/:id`,
+        handler: async (data) => await ApiController.getCacheEntry(data)
+      },
+      {
+        method: "GET",
+        path: `${basePath}/api/exceptions`,
+        handler: async (data) => await ApiController.getExceptions(data)
+      },
+      {
+        method: "GET",
+        path: `${basePath}/api/exceptions/:id`,
+        handler: async (data) => await ApiController.getException(data)
+      },
       {
         method: "DELETE",
         path: `${basePath}/api/truncate`,