@hatk/hatk 0.0.1-alpha.4 → 0.0.1-alpha.41

package/dist/indexer.js

@@ -1,11 +1,11 @@
 import { cborDecode } from "./cbor.js";
 import { parseCarFrame } from "./car.js";
-import { insertRecord, deleteRecord, setCursor, setRepoStatus, getRepoRetryInfo, listAllRepoStatuses } from "./db.js";
+import { insertRecord, deleteRecord, setCursor, setRepoStatus, getRepoRetryInfo, listAllRepoStatuses, getDatabasePort, } from "./database/db.js";
 import { backfillRepo } from "./backfill.js";
-import { rebuildAllIndexes } from "./fts.js";
+import { rebuildAllIndexes } from "./database/fts.js";
 import { log, emit, timer } from "./logger.js";
 import { runLabelRules } from "./labels.js";
-import { getLexiconArray } from "./schema.js";
+import { getLexiconArray } from "./database/schema.js";
 import { validateRecord } from '@bigmoves/lexicon';
 let buffer = [];
 let flushTimer = null;
@@ -18,7 +18,8 @@ let ftsRebuildInterval = 500;
 const pendingBuffers = new Map();
 // Track in-flight backfills to avoid duplicates
 const backfillInFlight = new Set();
-const MAX_CONCURRENT_BACKFILLS = 5;
+const backfillPromises = new Map();
+const pendingReschedule = new Set();
 // In-memory cache of repo status to avoid flooding the DB read queue
 const repoStatusCache = new Map();
 // Set by startIndexer
@@ -27,6 +28,12 @@ let indexerSignalCollections;
 let indexerPinnedRepos = null;
 let indexerFetchTimeout;
 let indexerMaxRetries;
+let maxConcurrentBackfills = 3;
+/**
+ * Flush the write buffer — insert all buffered records, update the relay cursor,
+ * run label rules on inserted records, and trigger FTS rebuilds when the write
+ * threshold is reached. Emits a wide event with batch stats.
+ */
 async function flushBuffer() {
     if (buffer.length === 0)
         return;
@@ -86,9 +93,14 @@ async function flushBuffer() {
     writesSinceRebuild += batch.length;
     if (writesSinceRebuild >= ftsRebuildInterval) {
         writesSinceRebuild = 0;
-        rebuildAllIndexes([...indexerCollections]).catch(() => { });
+        // Skip periodic full rebuild for SQLite — it uses incremental FTS updates
+        const port = getDatabasePort();
+        if (port.dialect !== 'sqlite') {
+            rebuildAllIndexes([...indexerCollections]).catch(() => { });
+        }
     }
 }
+/** Schedule a flush after FLUSH_INTERVAL_MS if one isn't already pending. */
 function scheduleFlush() {
     if (flushTimer)
         return;
@@ -97,6 +109,7 @@ function scheduleFlush() {
         await flushBuffer();
     }, FLUSH_INTERVAL_MS);
 }
+/** Add a record to the write buffer. Flushes immediately if BATCH_SIZE is reached. */
 function bufferWrite(item) {
     buffer.push(item);
     if (buffer.length >= BATCH_SIZE) {
@@ -110,11 +123,39 @@ function bufferWrite(item) {
         scheduleFlush();
     }
 }
+/**
+ * Auto-backfill a DID's repo when first seen on the firehose.
+ *
+ * Fetches the full repo via CAR export, inserts all records, then replays any
+ * firehose events that arrived during the backfill. Concurrency is capped at
+ * `maxConcurrentBackfills`. Failed backfills retry with exponential delay up
+ * to `maxRetries`.
+ */
+/** Wait for a DID's backfill to complete if one is in flight. */
+export function awaitBackfill(did) {
+    const entry = backfillPromises.get(did);
+    return entry ? entry.promise : Promise.resolve();
+}
 export async function triggerAutoBackfill(did, attempt = 0) {
     if (backfillInFlight.has(did))
         return;
+    if (backfillInFlight.size >= maxConcurrentBackfills) {
+        if (!pendingReschedule.has(did)) {
+            pendingReschedule.add(did);
+            setTimeout(() => {
+                pendingReschedule.delete(did);
+                triggerAutoBackfill(did, attempt);
+            }, 10_000);
+        }
+        return;
+    }
     backfillInFlight.add(did);
     pendingBuffers.set(did, []);
+    if (!backfillPromises.has(did)) {
+        let resolveBackfill;
+        const promise = new Promise((r) => { resolveBackfill = r; });
+        backfillPromises.set(did, { promise, resolve: resolveBackfill });
+    }
     if (attempt === 0)
         await setRepoStatus(did, 'pending');
     const elapsed = timer();
@@ -154,6 +195,12 @@ export async function triggerAutoBackfill(did, attempt = 0) {
         error,
         retry_count: currentRetryCount,
     });
+    // Resolve awaiting callers (e.g. on-login hooks)
+    const entry = backfillPromises.get(did);
+    if (entry) {
+        entry.resolve();
+        backfillPromises.delete(did);
+    }
     if (status === 'error' && currentRetryCount < indexerMaxRetries) {
         const delaySecs = Math.min(currentRetryCount * 60, 3600);
         const delayMs = Math.max(delaySecs, 60) * 1000;
@@ -162,7 +209,7 @@ export async function triggerAutoBackfill(did, attempt = 0) {
         }, delayMs);
     }
 }
-// Periodic memory diagnostics
+/** Emit a memory diagnostics wide event every 30s for observability. */
 function startMemoryDiagnostics() {
     setInterval(() => {
         const mem = process.memoryUsage();
@@ -184,6 +231,16 @@ function startMemoryDiagnostics() {
         });
     }, 30_000);
 }
+/**
+ * Connect to the AT Protocol relay firehose and begin indexing.
+ *
+ * Opens a WebSocket to `subscribeRepos`, processes commit messages synchronously
+ * on the event loop to minimize backpressure, and batches writes through
+ * {@link flushBuffer}. New DIDs trigger auto-backfill via {@link triggerAutoBackfill}.
+ * Reconnects automatically on disconnect after a 3s delay.
+ *
+ * @returns The WebSocket connection (for shutdown coordination)
+ */
 export async function startIndexer(opts) {
     const { relayUrl, collections, cursor, fetchTimeout } = opts;
     if (opts.ftsRebuildInterval != null)
@@ -193,6 +250,7 @@ export async function startIndexer(opts) {
     indexerPinnedRepos = opts.pinnedRepos || null;
     indexerFetchTimeout = fetchTimeout;
     indexerMaxRetries = opts.maxRetries;
+    maxConcurrentBackfills = opts.parallelism ?? 3;
     // Pre-populate repo status cache from DB so non-signal updates
     // (e.g. profile changes) are processed for already-tracked DIDs
     if (repoStatusCache.size === 0) {
@@ -231,6 +289,11 @@ export async function startIndexer(opts) {
     });
     return ws;
 }
+/**
+ * Process a single firehose message. Decodes the CBOR header/body, filters
+ * for relevant collections, validates records against lexicons, and routes
+ * writes to the buffer (or pending buffer if the DID is mid-backfill).
+ */
 function processMessage(bytes, collections) {
     const header = cborDecode(bytes, 0);
     const body = cborDecode(bytes, header.offset);
@@ -264,7 +327,7 @@ function processMessage(bytes, collections) {
         repoStatusCache.set(did, 'unknown');
     }
     if (hasSignalOp && (!indexerPinnedRepos || indexerPinnedRepos.has(did))) {
-        if (repoStatus === null && backfillInFlight.size < MAX_CONCURRENT_BACKFILLS) {
+        if (repoStatus === null && backfillInFlight.size < maxConcurrentBackfills) {
             repoStatusCache.set(did, 'pending');
             triggerAutoBackfill(did);
         }

package/dist/labels.d.ts

@@ -13,7 +13,34 @@ export interface LabelRuleContext {
         value: Record<string, any>;
     };
 }
+export interface LabelModule {
+    definition?: LabelDefinition;
+    evaluate?: (ctx: LabelRuleContext) => Promise<string[]>;
+}
+export declare function defineLabel(module: LabelModule): {
+    definition?: LabelDefinition;
+    evaluate?: (ctx: LabelRuleContext) => Promise<string[]>;
+    __type: "labels";
+};
+/**
+ * Discover and load label rule modules from the `labels/` directory.
+ *
+ * Each module should default-export an object with an optional `definition`
+ * (label metadata like severity and blur behavior) and an optional `evaluate`
+ * function that returns label values to apply to a record.
+ *
+ * @param labelsDir - Absolute path to the `labels/` directory
+ */
 export declare function initLabels(labelsDir: string): Promise<void>;
+/** Register a single label module from a scanned server/ module. */
+export declare function registerLabelModule(name: string, labelMod: {
+    definition?: LabelDefinition;
+    evaluate?: (ctx: LabelRuleContext) => Promise<string[]>;
+}): void;
+/**
+ * Evaluate all loaded label rules against a record and persist any resulting labels.
+ * Called after each record is indexed. Rule errors are logged but never block indexing.
+ */
 export declare function runLabelRules(record: {
     uri: string;
     cid: string;
@@ -21,9 +48,16 @@ export declare function runLabelRules(record: {
     collection: string;
     value: Record<string, any>;
 }): Promise<void>;
+/**
+ * Re-evaluate all label rules against every existing record in the given collections.
+ * Used by `/admin/rescan-labels` to apply new or updated rules retroactively.
+ *
+ * @returns Count of records scanned and new labels applied
+ */
 export declare function rescanLabels(collections: string[]): Promise<{
     scanned: number;
     labeled: number;
 }>;
+/** Return all label definitions discovered during {@link initLabels}. */
 export declare function getLabelDefinitions(): LabelDefinition[];
 //# sourceMappingURL=labels.d.ts.map

package/dist/labels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../src/labels.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAIlD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;IACD,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC3B,CAAA;CACF;AAWD,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCjE;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCvG;AAED,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAEvD"}
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../src/labels.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAIlD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;IACD,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC3B,CAAA;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CACxD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW;iBAJhC,eAAe;eACjB,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;;EAKxD;AAYD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCjE;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;IAAE,UAAU,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GAClG,IAAI,CAON;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCvG;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAEvD"}

package/dist/labels.js

@@ -6,13 +6,53 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Label system for applying moderation labels to records as they are indexed.
+ *
+ * Place label modules in the `labels/` directory. Each module default-exports
+ * an object with a `definition` (label metadata) and/or an `evaluate` function
+ * (rule that returns label values for a given record).
+ *
+ * @example
+ * ```ts
+ * // labels/nsfw.ts
+ * import type { LabelRuleContext } from '@hatk/hatk/labels'
+ *
+ * export default {
+ *   definition: {
+ *     identifier: 'nsfw',
+ *     severity: 'alert',
+ *     blurs: 'media',
+ *     defaultSetting: 'warn',
+ *     locales: [{ lang: 'en', name: 'NSFW', description: 'Not safe for work' }],
+ *   },
+ *
+ *   async evaluate(ctx: LabelRuleContext): Promise<string[]> {
+ *     if (ctx.record.value.nsfw === true) return ['nsfw']
+ *     return []
+ *   },
+ * }
+ * ```
+ */
 import { resolve } from 'node:path';
 import { readdirSync } from 'node:fs';
-import { querySQL, runSQL, insertLabels, getSchema } from "./db.js";
+import { querySQL, runSQL, insertLabels, getSchema } from "./database/db.js";
 import { log, emit } from "./logger.js";
+export function defineLabel(module) {
+    return { __type: 'labels', ...module };
+}
 const rules = [];
 let labelDefs = [];
 let labelSrc = 'self';
+/**
+ * Discover and load label rule modules from the `labels/` directory.
+ *
+ * Each module should default-export an object with an optional `definition`
+ * (label metadata like severity and blur behavior) and an optional `evaluate`
+ * function that returns label values to apply to a record.
+ *
+ * @param labelsDir - Absolute path to the `labels/` directory
+ */
 export async function initLabels(labelsDir) {
     let files;
     try {
@@ -26,7 +66,7 @@ export async function initLabels(labelsDir) {
     for (const file of files) {
         const name = file.replace(/\.(ts|js)$/, '');
         const scriptPath = resolve(labelsDir, file);
-        const mod = await import(__rewriteRelativeImportExtension(scriptPath));
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
         const handler = mod.default;
         if (handler.definition) {
             labelDefs.push(handler.definition);
@@ -45,6 +85,19 @@ export async function initLabels(labelsDir) {
         log(`[labels] ${labelDefs.length} label definitions loaded`);
     }
 }
+/** Register a single label module from a scanned server/ module. */
+export function registerLabelModule(name, labelMod) {
+    if (labelMod.definition) {
+        labelDefs.push(labelMod.definition);
+    }
+    if (labelMod.evaluate) {
+        rules.push({ name, evaluate: labelMod.evaluate });
+    }
+}
+/**
+ * Evaluate all loaded label rules against a record and persist any resulting labels.
+ * Called after each record is indexed. Rule errors are logged but never block indexing.
+ */
 export async function runLabelRules(record) {
     if (rules.length === 0)
         return;
@@ -69,15 +122,21 @@ export async function runLabelRules(record) {
         emit('labels', 'applied', { count: allLabels.length, uri: record.uri, vals: allLabels.map((l) => l.val) });
     }
 }
+/**
+ * Re-evaluate all label rules against every existing record in the given collections.
+ * Used by `/admin/rescan-labels` to apply new or updated rules retroactively.
+ *
+ * @returns Count of records scanned and new labels applied
+ */
 export async function rescanLabels(collections) {
-    const beforeRows = await querySQL(`SELECT COUNT(*) as count FROM _labels`);
+    const beforeRows = (await querySQL(`SELECT COUNT(*) as count FROM _labels`));
     const beforeCount = Number(beforeRows[0]?.count || 0);
     let scanned = 0;
     for (const collection of collections) {
         const schema = getSchema(collection);
         if (!schema)
             continue;
-        const rows = await querySQL(`SELECT * FROM ${schema.tableName}`);
+        const rows = (await querySQL(`SELECT * FROM ${schema.tableName}`));
         for (const row of rows) {
             scanned++;
             const value = {};
@@ -85,7 +144,7 @@ export async function rescanLabels(collections) {
                 let v = row[col.name];
                 if (v === null || v === undefined)
                     continue;
-                if (col.duckdbType === 'JSON' && typeof v === 'string') {
+                if (col.isJson && typeof v === 'string') {
                     try {
                         v = JSON.parse(v);
                     }
@@ -102,10 +161,11 @@ export async function rescanLabels(collections) {
             });
         }
     }
-    const afterRows = await querySQL(`SELECT COUNT(*) as count FROM _labels`);
+    const afterRows = (await querySQL(`SELECT COUNT(*) as count FROM _labels`));
     const afterCount = Number(afterRows[0]?.count || 0);
     return { scanned, labeled: afterCount - beforeCount };
 }
+/** Return all label definitions discovered during {@link initLabels}. */
 export function getLabelDefinitions() {
     return labelDefs;
 }

package/dist/logger.d.ts

@@ -1,4 +1,33 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export declare function log(...args: unknown[]): void;
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export declare function emit(module: string, op: string, fields: Record<string, unknown>): void;
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export declare function timer(): () => number;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}

package/dist/logger.js

@@ -1,8 +1,28 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export function log(...args) {
     if (process.env.DEBUG === '0')
         return;
     console.log(...args);
 }
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export function emit(module, op, fields) {
     if (process.env.DEBUG === '0')
         return;
@@ -17,6 +37,15 @@ export function emit(module, op, fields) {
     }
     process.stdout.write(JSON.stringify(entry) + '\n');
 }
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export function timer() {
     const start = performance.now();
     return () => Math.round(performance.now() - start);