dbtour 0.2.4 → 0.3.0

package/dist/model.d.ts

@@ -22,6 +22,17 @@ export interface Constraint {
     columns: string[];
     definition?: string;
 }
+/**
+ * How big a table is, as the database keeps it about itself: counted from its catalogue, never by reading
+ * rows, so the count is the database's own estimate. Absent when the source could not read it.
+ */
+export interface TableStats {
+    rows: number;
+    /** The pages the rows take, the heap or clustered index, in bytes. */
+    dataBytes: number;
+    /** The pages every other index takes, in bytes. */
+    indexBytes: number;
+}
 export interface Table {
     name: string;
     kind: 'table' | 'view';
@@ -32,6 +43,7 @@ export interface Table {
     constraints: Constraint[];
     /** The SQL of a view. */
     definition?: string;
+    stats?: TableStats;
 }
 export interface Schema {
     name: string;
@@ -55,6 +67,8 @@ export interface Database {
     driver: string;
     version?: string;
     description?: string;
+    /** When the source read its tables' stats, as an ISO timestamp: they change, so they carry their moment. */
+    statsReadAt?: string;
     schemas: Schema[];
     relations: Relation[];
 }

package/dist/model.js

@@ -113,6 +113,7 @@ function checkDatabase(check, d, p) {
     check.string(d.driver, `${p}.driver`);
     check.optionalString(d.version, `${p}.version`);
     check.optionalString(d.description, `${p}.description`);
+    check.optionalString(d.statsReadAt, `${p}.statsReadAt`);
     check.list(d.schemas, `${p}.schemas`, (s, sp) => {
         if (!check.object(s, sp))
             return;
@@ -141,6 +142,10 @@ function checkTable(check, t, p) {
         check.errors.push(`${p}.kind must be "table" or "view"`);
     check.optionalString(t.description, `${p}.description`);
     check.optionalString(t.definition, `${p}.definition`);
+    if (t.stats !== undefined && check.object(t.stats, `${p}.stats`)) {
+        for (const field of ['rows', 'dataBytes', 'indexBytes'])
+            check.count(t.stats[field], `${p}.stats.${field}`);
+    }
     if (t.primaryKey !== undefined)
         check.strings(t.primaryKey, `${p}.primaryKey`);
     check.list(t.columns, `${p}.columns`, (c, cp) => {
@@ -196,6 +201,10 @@ class Checker {
         if (value !== undefined && typeof value !== 'boolean')
             this.errors.push(`${path} must be true or false when given`);
     }
+    count(value, path) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+            this.errors.push(`${path} must be a number of 0 or more`);
+    }
     strings(value, path) {
         if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
             this.errors.push(`${path} must be a list of strings`);

package/dist/render/markdown.d.ts

@@ -1,8 +1,14 @@
-import { findTable, type Model } from '../model.ts';
+import { findTable, type Model, type TableStats } from '../model.ts';
 export declare const wholeDiagramLimit = 40;
 export declare function renderMarkdown(model: Model): Record<string, string>;
 /** The product's name for a driver: mssql is SQL Server. */
 export declare function driverName(driver: string): string;
+/** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
+export declare function formatCount(n: number): string;
+/** 480 KB, 7.1 MB, 102 MB: binary units, as the database counts its pages, with one decimal below ten. */
+export declare function formatBytes(bytes: number): string;
+/** The sentence under a table's title: the count is the database's estimate, so it says about, and when. */
+export declare function statsLine(stats: TableStats, readAt?: string): string;
 /** One table's page on its own: what the page hands to an agent. */
 export declare function renderTableMarkdown(model: Model, ref: string): string;
 export { findTable };

package/dist/render/markdown.js

@@ -11,7 +11,7 @@ export function renderMarkdown(model) {
         for (const schema of database.schemas) {
             for (const table of schema.tables) {
                 const ref = tableRef(schema.name, table.name);
-                files[`tables/${ref}.md`] = renderTable(model, ref, table);
+                files[`tables/${ref}.md`] = renderTable(model, ref, table, database);
             }
         }
     }
@@ -27,11 +27,14 @@ function renderIndex(model) {
         if (database.description)
             parts.push(`${database.description}\n`);
         parts.push(`${driverLine(database)}\n`);
-        parts.push('| Table | Kind | Columns | Description |\n|---|---|---|---|');
+        // Rows and size only when the source read them; a view, which keeps no rows of its own, leaves them blank.
+        const sized = database.schemas.some((s) => s.tables.some((t) => t.stats));
+        parts.push(sized ? '| Table | Kind | Columns | Rows | Size | Description |\n|---|---|---|---|---|---|' : '| Table | Kind | Columns | Description |\n|---|---|---|---|');
         for (const schema of database.schemas) {
             for (const table of schema.tables) {
                 const ref = tableRef(schema.name, table.name);
-                parts.push(`| [${ref}](tables/${ref}.md) | ${table.kind} | ${table.columns.length} | ${cell(table.description)} |`);
+                const size = !sized ? '' : table.stats ? ` ${formatCount(table.stats.rows)} | ${formatBytes(table.stats.dataBytes + table.stats.indexBytes)} |` : '  |  |';
+                parts.push(`| [${ref}](tables/${ref}.md) | ${table.kind} | ${table.columns.length} |${size} ${cell(table.description)} |`);
             }
         }
         parts.push('');
@@ -62,17 +65,40 @@ function driverLine(database) {
     const name = driverName(database.driver);
     return database.version ? `${name} ${database.version}.` : `${name}.`;
 }
+/** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
+export function formatCount(n) {
+    return String(Math.round(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+const byteUnits = ['B', 'KB', 'MB', 'GB', 'TB'];
+/** 480 KB, 7.1 MB, 102 MB: binary units, as the database counts its pages, with one decimal below ten. */
+export function formatBytes(bytes) {
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < byteUnits.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    const text = unit === 0 || value >= 10 ? String(Math.round(value)) : value.toFixed(1).replace(/\.0$/, '');
+    return `${text} ${byteUnits[unit]}`;
+}
+/** The sentence under a table's title: the count is the database's estimate, so it says about, and when. */
+export function statsLine(stats, readAt) {
+    const when = readAt ? `, as the database counted them on ${readAt.slice(0, 10)}` : '';
+    return `About ${formatCount(stats.rows)} rows · ${formatBytes(stats.dataBytes)} of data · ${formatBytes(stats.indexBytes)} of indexes${when}.`;
+}
 /** One table's page on its own: what the page hands to an agent. */
 export function renderTableMarkdown(model, ref) {
     const found = findTable(model, ref);
     if (!found)
         throw new Error(`${ref} is not a table in the model`);
-    return renderTable(model, ref, found.table);
+    return renderTable(model, ref, found.table, found.database);
 }
-function renderTable(model, ref, table) {
+function renderTable(model, ref, table, database) {
     const parts = [`# ${ref}\n`];
     if (table.description)
         parts.push(`${table.description}\n`);
+    if (table.stats)
+        parts.push(`${statsLine(table.stats, database.statsReadAt)}\n`);
     const relations = relationsOf(model, ref);
     parts.push('| Column | Type | Nullable | Default | Key | Description |\n|---|---|---|---|---|---|');
     for (const column of table.columns) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",