logsheet

logsheet is a small Express-friendly logging viewer for runtime flows that need more structure than console output.

It stores log entries in SQLite, serves an HTML viewer for browsing sheets, and streams new entries over SSE for live monitoring.

Install

npm install logsheet better-sqlite3 express

Usage

import express from "express";
import { Logsheet } from "logsheet";

const app = express();

const logsheet = new Logsheet({
  basePath: "/logsheet",
  publicOrigin: "https://example.com",
});

app.use("/logsheet", logsheet.handler());

const sheet = logsheet.create({
  title: "Inbound chat run",
  metadata: { chatId: 42 },
});

sheet.log({
  group: "ingress",
  title: "User message received",
  payload: { role: "user", content: "Hello" },
});

Open /logsheet to see the list view, then click into a sheet for the live stream.

API

new Logsheet(config?)

• dbPath?: string
• basePath?: string
• publicOrigin?: string
• staleSheetMs?: number

logsheet.handler()

Returns an Express router that serves:

• GET / list page
• GET /:id sheet page
• GET /:id/entries JSON entries
• GET /:id/stream SSE stream
• GET /:id/groups JSON groups

logsheet.create(options)

Creates a new sheet and returns a Sheet.

• title: string
• metadata?: Record<string, unknown>

sheet.log(options)

Appends a log entry and broadcasts it to connected viewers.

• title: string
• group?: string
• parentId?: string
• level?: "info" | "warn" | "error" | "debug"
• payload?: unknown

sheet.touch()

Updates the sheet timestamp without writing an entry.

sheet.close()

Marks the sheet as closed and emits a close event to viewers.

Development

npm install
npm run build

License

MIT